<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->

<!-- Mirrored from minetest.gitlab.io/minetest/groups/ by HTTrack Website Copier/3.x [XR&CO'2014], Thu, 01 Oct 2020 14:46:27 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=utf-8" /><!-- /Added by HTTrack -->
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  
  
  <link rel="shortcut icon" href="../img/favicon.ico">
  <title>Groups - Minetest API Documentation</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />

  <link rel="stylesheet" href="../css/theme.css" />
  <link rel="stylesheet" href="../css/theme_extra.css" />
  <link href="../css/code_styles.css" rel="stylesheet" />
  <link href="../css/extra.css" rel="stylesheet" />
  
  <script>
    // Current page data
    var mkdocs_page_name = "Groups";
    var mkdocs_page_input_path = "groups.md";
    var mkdocs_page_url = null;
  </script>
  
  <script src="../js/jquery-2.1.1.min.js" defer></script>
  <script src="../js/modernizr-2.8.3.min.js" defer></script> 
  
</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
    <div class="wy-side-scroll">
      <div class="wy-side-nav-search">
        <a href="../index.html" class="icon icon-home"> Minetest API Documentation</a>
        <div role="search">
  <form id ="rtd-search-form" class="wy-form" action="http://minetest.gitlab.io/minetest/search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" title="Type search term here" />
  </form>
</div>
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../games/index.html">Games</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../mods/index.html">Mods</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../aliases/index.html">Aliases</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../textures/index.html">Textures</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../sounds/index.html">Sounds</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../registered-definitions/index.html">Registered definitions</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../nodes/index.html">Nodes</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../map-terminology-and-coordinates/index.html">Map terminology and coordinates</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../hud/index.html">HUD</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../representations-of-simple-things/index.html">Representations of simple things</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../flag-specifier-format/index.html">Flag Specifier Format</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../items/index.html">Items</a>
                    </li>
                </ul>
                <ul class="current">
                    <li class="toctree-l1 current"><a class="reference internal current" href="index.html">Groups</a>
    <ul class="current">
    <li class="toctree-l2"><a class="reference internal" href="#usage">Usage</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#groups-of-items">Groups of items</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#groups-of-nodes">Groups of nodes</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#groups-of-entities">Groups of entities</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#groups-of-tools">Groups of tools</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#groups-in-crafting-recipes">Groups in crafting recipes</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#special-groups">Special groups</a>
        <ul>
    <li class="toctree-l3"><a class="reference internal" href="#node-item-and-tool-groups">Node, item and tool groups</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#node-only-groups">Node-only groups</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#tool-only-groups">Tool-only groups</a>
    </li>
    <li class="toctree-l3"><a class="reference internal" href="#objectref-groups">ObjectRef groups</a>
    </li>
        </ul>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#known-damage-and-digging-time-defining-groups">Known damage and digging time defining groups</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#examples-of-custom-groups">Examples of custom groups</a>
    </li>
    <li class="toctree-l2"><a class="reference internal" href="#digging-time-calculation-specifics">Digging time calculation specifics</a>
    </li>
    </ul>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../entity-damage-mechanism/index.html">Entity damage mechanism</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../metadata/index.html">Metadata</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../formspec/index.html">Formspec</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../inventory/index.html">Inventory</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../colors/index.html">Colors</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../escape-sequences/index.html">Escape sequences</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../spatial-vectors/index.html">Spatial Vectors</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../helper-functions/index.html">Helper functions</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../perlin-noise/index.html">Perlin noise</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../ores/index.html">Ores</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../decoration-types/index.html">Decoration types</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../schematics/index.html">Schematics</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../lua-voxel-manipulator/index.html">Lua Voxel Manipulator</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../mapgen-objects/index.html">Mapgen objects</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../registered-entities/index.html">Registered entities</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../l-system-trees/index.html">L-system trees</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../minetest-namespace-reference/index.html">'minetest' namespace reference</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../class-reference/index.html">Class reference</a>
                    </li>
                </ul>
                <ul>
                    <li class="toctree-l1"><a class="reference internal" href="../definition-tables/index.html">Definition tables</a>
                    </li>
                </ul>
      </div>
    </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="../index.html">Minetest API Documentation</a>
      </nav>

      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="../index.html">Docs</a> &raquo;</li>
    
      
    
    <li>Groups</li>
    <li class="wy-breadcrumbs-aside">
      
    </li>
  </ul>
  
  <hr/>
</div>
          <div role="main">
            <div class="section">
              
                <h1 id="groups">Groups<a class="headerlink" href="#groups" title="Permanent link">&para;</a></h1>
<p>In a number of places, there is a group table. Groups define the
properties of a thing (item, node, armor of entity, capabilities of
tool) in such a way that the engine and other mods can can interact with
the thing without actually knowing what the thing is.</p>
<h2 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">&para;</a></h2>
<p>Groups are stored in a table, having the group names with keys and the
group ratings as values. Group ratings are integer values within the
range [-32767, 32767]. For example:</p>
<div class="codehilite"><pre><span></span><code><span class="c1">-- Default dirt</span>
<span class="n">groups</span> <span class="o">=</span> <span class="err">{</span><span class="n">crumbly</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">soil</span><span class="o">=</span><span class="mi">1</span><span class="err">}</span>

<span class="c1">-- A more special dirt-kind of thing</span>
<span class="n">groups</span> <span class="o">=</span> <span class="err">{</span><span class="n">crumbly</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">soil</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="k">level</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">outerspace</span><span class="o">=</span><span class="mi">1</span><span class="err">}</span>
</code></pre></div>

<p>Groups always have a rating associated with them. If there is no
useful meaning for a rating for an enabled group, it shall be <code>1</code>.</p>
<p>When not defined, the rating of a group defaults to <code>0</code>. Thus when you
read groups, you must interpret <code>nil</code> and <code>0</code> as the same value, <code>0</code>.</p>
<p>You can read the rating of a group for an item or a node by using</p>
<div class="codehilite"><pre><span></span><code><span class="err">minetest.get_item_group(itemname, groupname)</span>
</code></pre></div>

<h2 id="groups-of-items">Groups of items<a class="headerlink" href="#groups-of-items" title="Permanent link">&para;</a></h2>
<p>Groups of items can define what kind of an item it is (e.g. wool).</p>
<h2 id="groups-of-nodes">Groups of nodes<a class="headerlink" href="#groups-of-nodes" title="Permanent link">&para;</a></h2>
<p>In addition to the general item things, groups are used to define whether
a node is destroyable and how long it takes to destroy by a tool.</p>
<h2 id="groups-of-entities">Groups of entities<a class="headerlink" href="#groups-of-entities" title="Permanent link">&para;</a></h2>
<p>For entities, groups are, as of now, used only for calculating damage.
The rating is the percentage of damage caused by tools with this damage group.
See [Entity damage mechanism].</p>
<div class="codehilite"><pre><span></span><code><span class="err">object.get_armor_groups() --&gt; a group-rating table (e.g. {fleshy=100})</span>
<span class="err">object.set_armor_groups({fleshy=30, cracky=80})</span>
</code></pre></div>

<h2 id="groups-of-tools">Groups of tools<a class="headerlink" href="#groups-of-tools" title="Permanent link">&para;</a></h2>
<p>Groups in tools define which groups of nodes and entities they are
effective towards.</p>
<h2 id="groups-in-crafting-recipes">Groups in crafting recipes<a class="headerlink" href="#groups-in-crafting-recipes" title="Permanent link">&para;</a></h2>
<p>An example: Make meat soup from any meat, any water and any bowl:</p>
<div class="codehilite"><pre><span></span><code><span class="err">{</span>
<span class="err">    output = &#39;food:meat_soup_raw&#39;,</span>
<span class="err">    recipe = {</span>
<span class="err">        {&#39;group:meat&#39;},</span>
<span class="err">        {&#39;group:water&#39;},</span>
<span class="err">        {&#39;group:bowl&#39;},</span>
<span class="err">    },</span>
<span class="err">    -- preserve = {&#39;group:bowl&#39;}, -- Not implemented yet (TODO)</span>
<span class="err">}</span>
</code></pre></div>

<p>Another example: Make red wool from white wool and red dye:</p>
<div class="codehilite"><pre><span></span><code><span class="err">{</span>
<span class="err">    type = &#39;shapeless&#39;,</span>
<span class="err">    output = &#39;wool:red&#39;,</span>
<span class="err">    recipe = {&#39;wool:white&#39;, &#39;group:dye,basecolor_red&#39;},</span>
<span class="err">}</span>
</code></pre></div>

<h2 id="special-groups">Special groups<a class="headerlink" href="#special-groups" title="Permanent link">&para;</a></h2>
<p>The asterisk <code>(*)</code> after a group name describes that there is no engine
functionality bound to it, and implementation is left up as a suggestion
to games.</p>
<h3 id="node-item-and-tool-groups">Node, item and tool groups<a class="headerlink" href="#node-item-and-tool-groups" title="Permanent link">&para;</a></h3>
<ul>
<li><code>not_in_creative_inventory</code>: (*) Special group for inventory mods to indicate
  that the item should be hidden in item lists.</li>
</ul>
<h3 id="node-only-groups">Node-only groups<a class="headerlink" href="#node-only-groups" title="Permanent link">&para;</a></h3>
<ul>
<li><code>attached_node</code>: if the node under it is not a walkable block the node will be
  dropped as an item. If the node is wallmounted the wallmounted direction is
  checked.</li>
<li><code>bouncy</code>: value is bounce speed in percent</li>
<li><code>connect_to_raillike</code>: makes nodes of raillike drawtype with same group value
  connect to each other</li>
<li><code>dig_immediate</code>: Player can always pick up node without reducing tool wear<ul>
<li><code>2</code>: the node always gets the digging time 0.5 seconds (rail, sign)</li>
<li><code>3</code>: the node always gets the digging time 0 seconds (torch)</li>
</ul>
</li>
<li><code>disable_jump</code>: Player (and possibly other things) cannot jump from node
  or if their feet are in the node. Note: not supported for <code>new_move = false</code></li>
<li><code>fall_damage_add_percent</code>: damage speed = <code>speed * (1 + value/100)</code></li>
<li><code>falling_node</code>: if there is no walkable block under the node it will fall</li>
<li><code>float</code>: the node will not fall through liquids</li>
<li><code>level</code>: Can be used to give an additional sense of progression in the game.<ul>
<li>A larger level will cause e.g. a weapon of a lower level make much less
   damage, and get worn out much faster, or not be able to get drops
   from destroyed nodes.</li>
<li><code>0</code> is something that is directly accessible at the start of gameplay</li>
<li>There is no upper limit</li>
<li>See also: <code>leveldiff</code> in [Tools]</li>
</ul>
</li>
<li><code>slippery</code>: Players and items will slide on the node.
  Slipperiness rises steadily with <code>slippery</code> value, starting at 1.</li>
</ul>
<h3 id="tool-only-groups">Tool-only groups<a class="headerlink" href="#tool-only-groups" title="Permanent link">&para;</a></h3>
<ul>
<li><code>disable_repair</code>: If set to 1 for a tool, it cannot be repaired using the
  <code>"toolrepair"</code> crafting recipe</li>
</ul>
<h3 id="objectref-groups"><code>ObjectRef</code> groups<a class="headerlink" href="#objectref-groups" title="Permanent link">&para;</a></h3>
<ul>
<li><code>immortal</code>: Skips all damage and breath handling for an object. This group
  will also hide the integrated HUD status bars for players, and is
  automatically set to all players when damage is disabled on the server.</li>
<li><code>punch_operable</code>: For entities; disables the regular damage mechanism for
  players punching it by hand or a non-tool item, so that it can do something
  else than take damage.</li>
</ul>
<h2 id="known-damage-and-digging-time-defining-groups">Known damage and digging time defining groups<a class="headerlink" href="#known-damage-and-digging-time-defining-groups" title="Permanent link">&para;</a></h2>
<ul>
<li><code>crumbly</code>: dirt, sand</li>
<li><code>cracky</code>: tough but crackable stuff like stone.</li>
<li><code>snappy</code>: something that can be cut using fine tools; e.g. leaves, small
  plants, wire, sheets of metal</li>
<li><code>choppy</code>: something that can be cut using force; e.g. trees, wooden planks</li>
<li><code>fleshy</code>: Living things like animals and the player. This could imply
  some blood effects when hitting.</li>
<li><code>explody</code>: Especially prone to explosions</li>
<li><code>oddly_breakable_by_hand</code>:
   Can be added to nodes that shouldn't logically be breakable by the
   hand but are. Somewhat similar to <code>dig_immediate</code>, but times are more
   like <code>{[1]=3.50,[2]=2.00,[3]=0.70}</code> and this does not override the
   speed of a tool if the tool can dig at a faster speed than this
   suggests for the hand.</li>
</ul>
<h2 id="examples-of-custom-groups">Examples of custom groups<a class="headerlink" href="#examples-of-custom-groups" title="Permanent link">&para;</a></h2>
<p>Item groups are often used for defining, well, <em>groups of items</em>.</p>
<ul>
<li><code>meat</code>: any meat-kind of a thing (rating might define the size or healing
  ability or be irrelevant -- it is not defined as of yet)</li>
<li><code>eatable</code>: anything that can be eaten. Rating might define HP gain in half
  hearts.</li>
<li><code>flammable</code>: can be set on fire. Rating might define the intensity of the
  fire, affecting e.g. the speed of the spreading of an open fire.</li>
<li><code>wool</code>: any wool (any origin, any color)</li>
<li><code>metal</code>: any metal</li>
<li><code>weapon</code>: any weapon</li>
<li><code>heavy</code>: anything considerably heavy</li>
</ul>
<h2 id="digging-time-calculation-specifics">Digging time calculation specifics<a class="headerlink" href="#digging-time-calculation-specifics" title="Permanent link">&para;</a></h2>
<p>Groups such as <code>crumbly</code>, <code>cracky</code> and <code>snappy</code> are used for this
purpose. Rating is <code>1</code>, <code>2</code> or <code>3</code>. A higher rating for such a group implies
faster digging time.</p>
<p>The <code>level</code> group is used to limit the toughness of nodes a tool can dig
and to scale the digging times / damage to a greater extent.</p>
<p><strong>Please do understand this</strong>, otherwise you cannot use the system to it's
full potential.</p>
<p>Tools define their properties by a list of parameters for groups. They
cannot dig other groups; thus it is important to use a standard bunch of
groups to enable interaction with tools.</p>
              
            </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="../tools/index.html" class="btn btn-neutral float-right" title="Tools">Next <span class="icon icon-circle-arrow-right"></span></a>
      
      
        <a href="../items/index.html" class="btn btn-neutral" title="Items"><span class="icon icon-circle-arrow-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <!-- Copyright etc -->
    
  </div>

  Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org/">Read the Docs</a>.
</footer>
      
        </div>
      </div>

    </section>

  </div>

  <div class="rst-versions" role="note" aria-label="versions">
    <span class="rst-current-version" data-toggle="rst-current-version">
      
      
        <span><a href="../items/index.html" style="color: #fcfcfc;">&laquo; Previous</a></span>
      
      
        <span style="margin-left: 15px"><a href="../tools/index.html" style="color: #fcfcfc">Next &raquo;</a></span>
      
    </span>
</div>
    <script>var base_url = '../index.html';</script>
    <script src="../js/theme.js" defer></script>
      <script src="../search/main.js" defer></script>
    <script defer>
        window.onload = function () {
            SphinxRtdTheme.Navigation.enable(true);
        };
    </script>

</body>

<!-- Mirrored from minetest.gitlab.io/minetest/groups/ by HTTrack Website Copier/3.x [XR&CO'2014], Thu, 01 Oct 2020 14:46:27 GMT -->
</html>
